home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 1998 November / IRIX 6.5.2 Base Documentation November 1998.img / usr / share / catman / u_man / cat3 / malloc_ss.z / malloc_ss
Text File  |  1998-10-30  |  12KB  |  199 lines
  1.  
  2.  
  3.  
  4. MMMMAAAALLLLLLLLOOOOCCCC____SSSSSSSS((((3333))))                                                      MMMMAAAALLLLLLLLOOOOCCCC____SSSSSSSS((((3333))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      malloc, free, realloc, calloc, memalign, valloc, ssmalloc_error -
  10.      SpeedShop memory allocation library
  11.  
  12. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  13.      ####iiiinnnncccclllluuuuddddeeee <<<<ssssttttddddlllliiiibbbb....hhhh>>>>
  14.  
  15.      vvvvooooiiiidddd ****mmmmaaaalllllllloooocccc ((((ssssiiiizzzzeeee____tttt ssssiiiizzzzeeee))));;;;
  16.  
  17.      vvvvooooiiiidddd ffffrrrreeeeeeee ((((vvvvooooiiiidddd ****ppppttttrrrr))));;;;
  18.  
  19.      vvvvooooiiiidddd ****rrrreeeeaaaalllllllloooocccc ((((vvvvooooiiiidddd ****ppppttttrrrr,,,, ssssiiiizzzzeeee____tttt ssssiiiizzzzeeee))));;;;
  20.  
  21.      vvvvooooiiiidddd ****ccccaaaalllllllloooocccc ((((ssssiiiizzzzeeee____tttt nnnneeeelllleeeemmmm,,,, ssssiiiizzzzeeee____tttt eeeellllssssiiiizzzzeeee))));;;;
  22.  
  23.      vvvvooooiiiidddd ****mmmmeeeemmmmaaaalllliiiiggggnnnn ((((ssssiiiizzzzeeee____tttt aaaalllliiiiggggnnnnmmmmeeeennnntttt,,,, ssssiiiizzzzeeee____tttt ssssiiiizzzzeeee))));;;;
  24.  
  25.      vvvvooooiiiidddd ****vvvvaaaalllllllloooocccc ((((ssssiiiizzzzeeee____tttt ssssiiiizzzzeeee))));;;;
  26.  
  27.      vvvvooooiiiidddd ssssssssmmmmaaaalllllllloooocccc____eeeerrrrrrrroooorrrr ((((cccchhhhaaaarrrr ****mmmmeeeessssssssaaaaggggeeee))));;;;
  28.  
  29. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  30.      The SpeedShop Performance Tools contain a malloc library, -lmalloc_ss,
  31.      which provides tracing and error detection around calls to the various
  32.      malloc routines.
  33.  
  34.      The library provides an intercept layer for calls to _m_a_l_l_o_c, _f_r_e_e,
  35.      _r_e_a_l_l_o_c, _m_e_m_a_l_i_g_n, and _v_a_l_l_o_c; the intercept allows tracing of all calls
  36.      with the SpeedShop performance tools.
  37.  
  38.      Calls to _m_a_l_l_o_c, _f_r_e_e, and _r_e_a_l_l_o_c are passed through to whatever memory
  39.      allocation library the program is linked with.  Calls to _c_a_l_l_o_c are
  40.      actually not intercepted, but rely on the underlying calloc to call
  41.      _m_a_l_l_o_c to get the space allocated.  Calls to _m_e_m_a_l_i_g_n are implemented by
  42.      allocating a block large enough to hold the aligned area asked for by the
  43.      user, as well as a guard area that holds a flag indicating that the user
  44.      block was obtained through memalign, and the address of the larger block.
  45.      Calls to _v_a_l_l_o_c are translated into a call to getpagesize, followed by a
  46.      memalign call.
  47.  
  48.      The last function, _s_s_m_a_l_l_o_c__e_r_r_o_r is nnnnooootttt a user-accessible function, it
  49.      is an internal static function.  It is called whenever any error is
  50.      detected, so that a debugger trap may be placed at exit from that routine
  51.      to interactively examine malloc errors.
  52.  
  53. MMMMAAAALLLLLLLLOOOOCCCC TTTTRRRRAAAACCCCIIIINNNNGGGG
  54.      The library provides for tracing of all calls to any of the entry points
  55.      listed above, as well as any of the errors listed below.  The trace is
  56.      normally captured using a SpeedShop performance experiment.  It may be
  57.      written in ASCII to stderr by enabling the environment variable
  58.      _SSMALLOC_TRACING, although this typically produces a great deal of
  59.      output.
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. MMMMAAAALLLLLLLLOOOOCCCC____SSSSSSSS((((3333))))                                                      MMMMAAAALLLLLLLLOOOOCCCC____SSSSSSSS((((3333))))
  71.  
  72.  
  73.  
  74. EEEERRRRRRRROOOORRRR DDDDEEEETTTTEEEECCCCTTTTIIIIOOOONNNN
  75.      The library will detect some errors under all conditions, and others if
  76.      _SSMALLOC_FASTCHK error detection is enabled.  All errors pass through
  77.      the routine _s_s_m_a_l_l_o_c__e_r_r_o_r and a trap can be placed at the exit from that
  78.      routine to catch the problem.  Errors are also traced.
  79.  
  80.      The errors that are always detected are:
  81.           _m_a_l_l_o_c call failing (returning NULL).
  82.           _r_e_a_l_l_o_c call failing (returning NULL).
  83.           _r_e_a_l_l_o_c call with an address outside the range of heap addresses
  84.           returned by _m_a_l_l_o_c or _m_e_m_a_l_i_g_n.
  85.           _m_e_m_a_l_i_g_n call with an improper alignment.
  86.           _f_r_e_e call with an address that is improperly aligned.
  87.           _f_r_e_e call with an address outside the range of heap addresses
  88.           returned by _m_a_l_l_o_c or _m_e_m_a_l_i_g_n.
  89.  
  90.      If _SSMALLOC_FASTCHK is enabled, the library will also detect:
  91.           _f_r_e_e or _r_e_a_l_l_o_c calls where the words prior to the user block have
  92.           been corrupted.
  93.           _f_r_e_e or _r_e_a_l_l_o_c calls where the words following the user block have
  94.           been corrupted.
  95.           _f_r_e_e or _r_e_a_l_l_o_c calls where the address is that of a block that has
  96.           already been freed.  This error may not always be detected if the
  97.           area around the block is reallocated after it was first freed.
  98.  
  99.      The behavior of the library is governed by various environment variables:
  100.  
  101.      ____SSSSPPPPEEEEEEEEDDDDSSSSHHHHOOOOPPPP____VVVVEEEERRRRBBBBOOOOSSSSEEEE
  102.           If set to a zero-length string, messages are printed to stderr only
  103.           when an error occurs.  If set to a non-zero length string), detailed
  104.           information about all traced events, including the callstack at the
  105.           time the error was detected, is printed.  This option is not
  106.           normally used by the end user, as it can produce a huge volume of
  107.           output.
  108.  
  109.      ____SSSSSSSSMMMMAAAALLLLLLLLOOOOCCCC____TTTTRRRRAAAACCCCIIIINNNNGGGG
  110.           enables tracing of all calls through the library.  Tracing is
  111.           normally done in the course of a performance experiment; the
  112.           variable need not be set in such cases, as the running of the
  113.           experiment will automatically enable it.  If the option is enabled
  114.           when the program is run independently, and _SSMALLOC_VERBOSE is set
  115.           to 2 or greater, the trace events and program call stacks will be
  116.           written to stderr.
  117.  
  118.      ____SSSSSSSSMMMMAAAALLLLLLLLOOOOCCCC____FFFFAAAASSSSTTTTCCCCHHHHKKKK
  119.           enables corruption detection for library calls.  Corruption
  120.           detection is done by allocating a space larger than the requested
  121.           area, and putting specific patterns in front of and behind the area
  122.           returned to the caller.  When _f_r_e_e is called, the patterns are
  123.           checked, and if the area was overwritten, an error message is
  124.           printed using an internal call to the routine _s_s_m_a_l_l_o_c__e_r_r_o_r. Under
  125.           the debugger, a trap may be set at exit from this routine to catch
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. MMMMAAAALLLLLLLLOOOOCCCC____SSSSSSSS((((3333))))                                                      MMMMAAAALLLLLLLLOOOOCCCC____SSSSSSSS((((3333))))
  137.  
  138.  
  139.  
  140.           the program at the error.
  141.  
  142.      ____SSSSSSSSMMMMAAAALLLLLLLLOOOOCCCC____FFFFUUUULLLLLLLLWWWWAAAARRRRNNNN
  143.           enables detection of some calls that are not strictly errors, but
  144.           represent sloppy programming, including _f_r_e_e(NULL), _m_a_l_l_o_c(0), and
  145.           _r_e_a_l_l_o_c(ptr,0).
  146.  
  147.      ____SSSSSSSSMMMMAAAALLLLLLLLOOOOCCCC____MMMMAAAAXXXXMMMMAAAALLLLLLLLOOOOCCCC nnnn
  148.           (where n is a non-zero integer, in any base) sets a maximum size for
  149.           any _m_a_l_l_o_c or _r_e_a_l_l_o_c or _m_e_m_a_l_i_g_n allocation.  Any request exceeding
  150.           that size will be flagged as an error, and return a NULL pointer.
  151.           Setting _SSMALLOC_MAXMALLOC to zero disables the test.  Note that
  152.           the size argument to malloc is an unsigned variable, and a small
  153.           negative number will be treated as a very large unsigned number, and
  154.           will typically trigger this error if _SSMALLOC_MAXMALLOC is set.
  155.  
  156.      ____SSSSSSSSMMMMAAAALLLLLLLLOOOOCCCC____NNNNOOOO____RRRREEEEUUUUSSSSEEEE
  157.           specifies that no area that has been freed will be reused.  With
  158.           this option enabled, no actual _f_r_e_e calls are really made, and the
  159.           process space and swap requirements can grow quite large.
  160.  
  161.      ____SSSSSSSSMMMMAAAALLLLLLLLOOOOCCCC____CCCCLLLLEEEEAAAARRRR____FFFFRRRREEEEEEEE
  162.           will clear the data upon any free call.  It will only work if
  163.           _SSMALLOC_FASTCHK is also enabled.
  164.  
  165.      ____SSSSSSSSMMMMAAAALLLLLLLLOOOOCCCC____CCCCLLLLEEEEAAAARRRR____FFFFRRRREEEEEEEE____PPPPAAAATTTTTTTTEEEERRRRNNNN <<<<ppppaaaatttttttteeeerrrrnnnn>>>>
  166.           specifies a pattern to clear the data if _SSMALLOC_CLEAR_FREE is
  167.           enabled.  The default pattern is 0xcafebeef for the 32-bit version,
  168.           and 0xcafebeefcafebeef for the 64-bit versions.  Only full words
  169.           (double words for 64-bits) are cleared to the pattern.
  170.  
  171.      ____SSSSSSSSMMMMAAAALLLLLLLLOOOOCCCC____CCCCLLLLEEEEAAAARRRR____MMMMAAAALLLLLLLLOOOOCCCC
  172.           will clear the memory area upon each allocation.  It also requires
  173.           _SSMALLOC_FASTCHK be enabled.
  174.  
  175.      ____SSSSSSSSMMMMAAAALLLLLLLLOOOOCCCC____CCCCLLLLEEEEAAAARRRR____MMMMAAAALLLLLLLLOOOOCCCC____PPPPAAAATTTTTTTTEEEERRRRNNNN <<<<ppppaaaatttttttteeeerrrrnnnn>>>>
  176.           specifies a pattern to clear the data if _SSMALLOC_CLEAR_MALLOC is
  177.           enabled.  The default pattern is 0xfacebeef for the 32-bit version,
  178.           and 0xfacebeeffacebeef for the 64-bit versions.  Only full words
  179.           (double words for 64-bits) are cleared to the pattern.
  180.  
  181. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  182.      malloc(3C), malloc(3X), ssrun(1), prof(1), ssdump(1), ssrt(3).
  183.  
  184. DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS
  185.      As ouput from the library routines.
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.